docs(factories): document Jira integration - #528
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dda424e to
59899c3
Compare
59899c3 to
a2eb24f
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Jira factories page with focused guidance for connecting Jira Cloud to a factory, configuring agent_session_created automations, understanding Rovo session continuity, permissions, delivery caveats, and troubleshooting. I reviewed the attached diff against the docs style guidance, link/comment/test expectations, the supplemental security checklist, and the provided spec context.
Concerns
- No blocking concerns found.
- No approved or repository spec context was provided for this PR, so there is no material spec drift to report.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Jira factory placeholder with a factory-specific guide for Rovo agent-session intake, filters, permissions, outputs, and troubleshooting. The page is generally scoped to factory behavior and no approved spec context was available for implementation drift review.
Concerns
- The setup step sends readers to the general Jira integration page, which continues into the label-triggered Jira run flow. Without anchoring or caveating the setup-only portion, factory readers can follow the wrong trigger path after connecting the app.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
a2eb24f to
e58f2e6
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Jira factory integration page with setup, trigger, filter, permissions, delivery-caveat, and troubleshooting guidance. I reviewed the attached diff, PR description, and spec context; no approved spec context was available, and I found no security-specific issues in the changed content.
Concerns
- The setup section only documents the definitions-as-code path even though the PR scope says the page covers both editor and definitions-as-code trigger paths. Add the editor setup path or narrow the documented scope before merge.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
e58f2e6 to
ac3061f
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Jira factory integration page with setup prerequisites, definitions-as-code trigger configuration, Rovo session behavior, permissions, delivery caveats, and troubleshooting. I found no approved spec context to compare against and no security-specific findings in the doc-only diff.
Concerns
- The first paragraph uses Rovo before defining it; adding a short definition makes the page more self-contained for readers who land here from search.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Jira factory integration placeholder with a focused page for connecting Jira Cloud to factories, configuring the agent_session_created trigger, understanding filters and session continuity, and handling permissions and troubleshooting. The attached spec context contains no approved spec to compare against, and the docs repo does not include a local security-review-pr companion; the security-sensitive authorization and filter caveats are covered clearly in the page.
Concerns
- No blocking concerns found in the attached diff.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-Authored-By: Warp Agent <agent@warp.dev> Co-Authored-By: Warp <agent@warp.dev>
ac3061f to
1c394f2
Compare
|
/oz-review |
|
You've used all 5 |
Editorial pass for external readers: - Lead with the user flow in plain language instead of internal routing vocabulary - Restructure setup into three clean steps with the automation example nested under its step, and explain the example inline - Consolidate trigger/filter behavior into one section, removing repeated explanations of when the event fires and keyword case-insensitivity - Replace internal jargon (seeds, intake, factory admission, issue mutations) with plain wording - Surface the filters-vs-access caveat as a caution callout and group permissions/reliability notes into a scannable list - Align title and headers with the sibling Linear page; use root-relative link for the platform setup page Co-Authored-By: Warp <agent@warp.dev>
|
Pushed an editorial pass (c7340ea) tightening this page for external readers:
No factual changes intended — all verified behaviors (event name, filter fields, status states, session continuity, dedup, authorization boundaries) are preserved. Validated with |
Reduce Rovo mentions from six to one. The remaining mention is a recognition pointer in prerequisites (Jira lists the Warp agent among Atlassian's Rovo agents); everywhere else the actors are Warp and the factory agent, and sessions are just agent sessions. Co-Authored-By: Warp <agent@warp.dev>
- Inline the app install and workspace connection steps instead of bouncing readers to the platform setup page mid-procedure; keep that page as a supplementary deep link and plainly note that its warp-agent label flow is for standalone cloud agents, not factories. - Note the agent runs in the cloud and link cloud agent session sharing for watching the full run from the factory. - Drop the repeated-deliveries bullet (internal dedup detail with no user action). - Reword the code-access bullet: connecting Jira grants no repository access, and agent PRs go through the usual review process. Co-Authored-By: Warp <agent@warp.dev>
|
Addressed the review feedback in 711b0f4:
Style lint and |
|
|
||
| A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. | ||
|
|
||
| :::caution |
There was a problem hiding this comment.
we should have something in the admin panel where we limit teams and jira project access. that is better to mention here over suggesting they limit the warp app's access.
There was a problem hiding this comment.
Checked the codebase: team/project Jira access scoping exists as an authorization policy layer (jira/jiraaccess) but isn't wired into webhook routing or MCP auth yet, and there's no admin-panel API for it yet (only specced in specs/jira-team-project-access/TECH.md). Didn't want to document an unshipped control, so I corrected the caution instead: access is workspace-wide today, with no team/project scoping available yet. Leaving this thread open for you and the requester to confirm.
Responding as wilson: Open session \u00b7 View factory task
- Document the automation editor's Jira trigger (Add trigger > Jira > Agent session created), now that the control room editor supports it alongside GitHub, GitLab, Linear, and Slack triggers. Keep definitions as code as the alternative path. - Correct the access caution: Jira access is workspace-wide today (no per-team or per-project scoping exists yet), so drop the inaccurate suggestion that the Warp app's Jira authorization can be scoped by project. - Remove the now-false claim that a new session on the same work item always starts a separate run. - Rewrite the Permissions bullet: the Jira user who starts a session must connect their Jira account to Warp before a run starts (new user-binding gate); the run still executes as the automation's agent, not as that Jira user. Co-Authored-By: Warp <agent@warp.dev>
- Add the missing per-factory Jira connection step (Settings > Jira > Connect/Install, select projects, Enable). Without it, the automation editor's Add trigger > Jira entry stays a disabled not-connected item (confirmed via AutomationEditor.tsx/TriggerMenu.tsx/ JiraIntegrationConnect.tsx and the editor's own test suite). - Correct the access caution: project_keys does control whether a given automation fires (provider_jira.go's evalFilter), it just isn't an access boundary across teams in the same workspace. Left the last sentence about no team/project scoping untouched. - Rewrite the Permissions bullet: a bound Jira actor becomes the run's creator/ActorUserID (automation_dispatch_jira.go), while the automation's agent remains the ExecutionPrincipal either way. - Make the definitions-as-code alternative self-contained (factory.yaml integration declaration + automation file path) instead of depending on the still-stubbed factory-as-code page. Co-Authored-By: Warp <agent@warp.dev>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
The review comments on this page are addressed in 159fabe9 and c60d39fe, and two findings are left for a human decision rather than a docs edit.
Concerns
- [question] The page documents flows that production has disabled.
factory_api,factory_automations, andjira_rovo_a2aare off inconfig/prod.yaml, andfeatures.JiraRovoA2AEnabledgates first-turn Jira sessions, so a public reader can neither open the documented Add trigger menu nor start the documented run. Publishing this page externally should wait for those launch flags, or the page needs the Early Access gating the launch foundation carries. - [question] Whether to publish the Jira access-scoping gap. Jason asked us to point at an admin-panel control that limits team and Jira project access; that control is not in the codebase —
jira/jiraaccess/policy.goholds policy helpers that webhook routing and MCP tool auth do not consult, and no admin API exists for it — so the caution states the current workspace-wide reality instead. See the inline comment for the sentence in question.
Verdict
Checks: build pass, tests n/a, CI pending (Build/link-check and Vercel still running), visual proof n/a
Found: 0 critical, 0 important, 0 suggestions, 0 nits, 2 questions
Responding as wilson: Open session · View factory task
| A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. | ||
|
|
||
| :::caution | ||
| Filters like `project_keys` decide whether *your* automation starts a run; they aren't an access boundary. A Jira event is evaluated against every team's automations in the connected workspace, so another team's automation with a broader or different filter can still start its own run on the same work item. Warp doesn't yet offer a way to scope Jira access by team or project. |
There was a problem hiding this comment.
[question] This sentence states a product limitation in external docs, which is a communication call rather than a docs-accuracy one. Source supports it as written — Jira admission expands across every team in the workspace (jira_forge_a2a.go), the per-team/per-project policy in jira/jiraaccess/policy.go is not consulted by webhook routing or MCP tool auth, and specs/jira-team-project-access/TECH.md still describes enforcement as proposed. Keep it, soften it, or drop it — and if the scoping control lands before launch, say the word and the page will document it instead.
Responding as wilson: Open session · View factory task
2 participants
Summary
Adds factory-specific Jira documentation covering app installation and workspace connection, editor and definitions-as-code trigger paths, issue continuity, routing filters, writeback, duplicate-safe repeated delivery, permissions, and troubleshooting.
Final size: 769 prose words. Generic provider installation details remain in the existing platform integration page; this PR focuses only on factory-specific behavior.
Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: 0 errorsnpm run build: 377 pages builtLatest source refresh
Rewrites Jira around the working Rovo agent-session model and documents only the emitted agent_session_created event.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@jasonkeung@liliwilson@captainsafiaScreenshots
Not included. The page uses a compact trigger/context/output table and links to the existing provider setup page; no approved factory-specific UI assets exist yet.
Unverified claims
None — UI labels, event classes, filters, authorization boundaries, continuity, and writeback behavior were verified against source.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plans: https://staging.warp.dev/drive/notebook/7ZPKWz7hM5I59o4Gg2ptYi and https://staging.warp.dev/drive/notebook/DpRWhMQ0DLCajPPMggXw5e
Co-Authored-By: Warp Agent agent@warp.dev